//--------------------------------------------------------------------------
// 
//  Copyright (c) Chili Software.  All rights reserved. 
// 
//  File: IRelationsNotification.cs
//
//  Description: Implemented to get notification on relations activities.
// 
//--------------------------------------------------------------------------

using System;
using System.Collections.Generic;
using System.Text;

namespace Chili.Opf3
{
	/// <summary>
	/// This interface is implemented by classes that need information on the persist of
	/// related persistent objects.
	/// </summary>
	/// <remarks>
	/// <para>
	/// Classes that need information about any persist of related persistents have to implement
	/// this interface to get notified about the changes. If the framework encounters a
	/// class implementing the interface the appropriate method is called while the related 
	/// persistent objects are persisted.
	/// </para>
	/// <para>
	/// Each method is called twice. Once before/after the relations marked with 
	/// <see cref="Chili.Opf3.Relations.PersistRelationships.ChildFirst">ChildFirst</see> and the other time before/after the 
	/// relations marked with <see cref="Chili.Opf3.Relations.PersistRelationships.ParentFirst">ParentFirst</see> are going to be saved.
	/// To understand which call is currently fired, check the <see cref="RelationsNotificationEventArgs">PersistRelationship</see> 
	/// property of the <see cref="RelationsNotificationEventArgs">RelationsNotificationEventArgs</see>.
	/// </para>
	/// </remarks>
	/// <example>
	///     The following example shows how to implement the interface in your own persistent
	///     classes.
	///     <code lang="CS">
	/// [Persistent("USER")]
	/// public class User : IRelationsNotification
	/// {
	///     void IRelationsNotification.OnBeforeRelationsPersist(RelationsNotificationEventArgs e)
	///     {
    ///         if (e.PersistentOperation == PersistentOperations.Delete)
	///         {
	///             this.Calls.RemoveAll();
	///             e.Context.PersistChanges(this.Calls, PersistDepths.Flat);
	///         }
	///     }
	///
	///     // ... Other methods of the interface.
	///
	///     // ... Other properties and code.
	/// }
	///     </code>
	/// </example>
	public interface IRelationsNotification
	{
		/// <summary>
		/// Invoked by the framework before the persistent's related objects are persisted.
		/// </summary>
		/// <param name="e">
		/// Contains information about the current operation, relationship type and the
		/// <see cref="Opf3.ObjectContext">ObjectContext</see> of the current operation.
		/// </param>
		void OnBeforeRelationsPersist(RelationsNotificationEventArgs e);

		/// <summary>
		/// Invoked by the framework after the persistent's related objects are persisted.
		/// </summary>
		/// <param name="e">
		/// Contains information about the current operation, relationship type and the
		/// <see cref="Opf3.ObjectContext">ObjectContext</see> of the current operation.
		/// </param>
		void OnAfterRelationsPersist(RelationsNotificationEventArgs e);
	}
}
